Shareware Super Platinum 8

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Super Platinum 8 / Shareware Super Platinum 8.iso / mac / MODEMPRO / ROBO42-A.ZIP;1 / SCRIPT.DOC < prev next >

Wrap

Text File | 1992-07-23 | 70.6 KB | 1,888 lines

¬ƒ¬ƒƒƒƒƒø ≥ ≥ ≥ ≥ √ƒƒƒ¬ƒŸ ⁄¬ƒƒø ¬¬ƒø ⁄¬ƒƒø ⁄¬ƒƒø ⁄¬ƒƒø ⁄¬ƒ¬ƒø ⁄¬ƒ¬ƒø (tm) ≥ ≥ ≥ ≥≥ ≥ ≥√ƒ¡ø ≥≥ ≥ ≥≥ ≥≥ ≥ ≥≥ ≥ ≥ ≥≥ ≥ ≥ ¡ƒ¡ ¡ƒƒ ¿¡ƒƒŸ ¡¡ƒƒŸ ¿¡ƒƒŸ ¿¡ƒƒŸ ¿¡ƒƒŸ ¡¡ ¡ ¡ ¡¡ ¡ ¡ ¬ ⁄ø ⁄ƒƒ¬ø The ultimate tool for unattended ¿ƒƒ¥≥ ⁄¬ƒ¡Ÿ BBS communications. ¿Ÿo¿¡ƒƒŸ ⁄ƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒø ≥ Script Language Reference ≥ ¿ƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒŸ (c) Copyright 1992, Parsons Consulting Table of Contents ROBOCOMM 4.1 SCRIPT PROCESSING ............................... 1 INTRODUCTION ................................................. 1 SCRIPT COMMENTS .............................................. 1 DOCUMENTATION SYNTAX ......................................... 1 LABELS ....................................................... 2 MACROS ....................................................... 2 PARAMETERS ................................................... 3 SCRIPT COMMANDS .............................................. 4 CAPTURE "<cFile>" [OVERWRITE | APPEND] ....................... 4 CD "<cDirectory>" ............................................ 5 CLEAR [WATCHES] .............................................. 5 CLOSE ........................................................ 5 COPY "<cSource>" [TO "<cTarget>"] ............................ 6 DELAY <nSeconds> ............................................. 6 DISABLE <nWatch> ............................................. 7 DOWNLOAD ["<cFileSpec>"] [USING "<cProtocol>"] ............... 7 ENABLE <nWatch> .............................................. 8 ERASE "<cFile>" .............................................. 9 EXIT <nReturnVal> ............................................ 9 GOSUB <label> ................................................ 9 GOTO <label> ................................................ 10 HANGUP ...................................................... 10 IF [NOT] <condition> ["<argument>"] <command> ............... 11 EMPTY ....................................................... 11 EXIST ....................................................... 11 DAY ......................................................... 11 DIR ......................................................... 11 CONNECTED ................................................... 12 ERRORLEVEL .................................................. 12 IMPORT ["A"|"D"] "<cFile>" [EXISTONLY] ...................... 12 JOIN "<cConference>" ........................................ 13 MD "<cDirectory>" ........................................... 13 MESSAGE "<cString>" ......................................... 13 NOTES "<cFile>" ............................................. 14 PARAMETER [nNumber] "<cPrompt>" ............................. 14 - i - Table of Contents PASSWORD "<cPassword>" ...................................... 14 RD "<cDirectory>" ........................................... 14 RENAME "<cfile>" [TO] "<cNewName>" .......................... 15 RENUMBER "<cFile>" [<nCount>] ............................... 15 RETURN ...................................................... 15 RUN "<cDosCommand>" [KEYBOARD "<cKeyString>"] ............... 16 SEND "<cString>" ............................................ 20 SOUND <nFrequency> <nDuration> .............................. 21 STATISTICS "<cFile>" ........................................ 22 TERMINAL .................................................... 22 TIMEOUT <nSeconds> .......................................... 22 TITLE "<cString>" ........................................... 22 UPLOAD "<cFileSpec>" [USING "<cProtocol>"] .................. 23 VENUE <cVenueCode> .......................................... 23 WAITFOR "<cString>" [FAILURE <command>] ..................... 24 WAITUNTIL ["<cTime>"] ["<cDate>"] ........................... 25 WHEN "<cString>" <command> .................................. 25 - ii - I. Robocomm 4.1 Script Processing * INTRODUCTION Robocomm's script processing system is a high level interpreted language designed to extend the automation capabilities of the software in instances where the pre-defined "Agenda Items" do not perform the service required. If you have done any programming at all on the PC, even at the batch file level, then Robocomm's script language should be fairly intuitive and straight-forward. The script commands are processed sequentially with the ability to jump to "labels" like DOS batch files using GOTO and GOSUB statements like BASIC programs. Perhaps the most significant capability of the script language is its ability to prompt the user for an unlimited number of parameters from the agenda creation/editing screen. This allows for a great deal of flexibility in the creation of "generic" scripts that will work on a wide variety of systems. At the time the "Execute Script" agenda item is created, the script itself asks the user to supply any needed information that is specific to the script run, such as a door number or a file name. In addition, all of the prompt definitions and other BBS-Specific information for each BBS can be accessed from within the script, allowing the script author to limit the amount of "hard coded" search text within the script. What all of this means is that it is now possible for people to create their own generic "agenda items" with Robocomm's script language. These scripts can then be distributed and run without modification by other Robocomm users! * SCRIPT COMMENTS You may place non-executable descriptive text anywhere you like within a script file, as long as it is on a line by itself and is preceded by a semicolon. * DOCUMENTATION SYNTAX _________________________________________________________________ Robocomm 4.1 - Script Language Reference Page: 1 As you read through this documentation, places where a command argument is to be entered by the script author are indicated between angle brackets <like this>. Text between angle brackets and also surrounded by quotation marks indicates that the script author is to input a word surrounded by quotation marks: "<cFile>" --> "robocomm.cap" Reserved Words (or COMMANDS) appear in all UPPER CASE. Optional command arguments are surrounded by square brackets [LIKE THIS]. When a choice between one or more command arguments is required, all available options will be listed, separated by the pipe symbol. Thus, an optional command argument with three choices will look like this: [ SEVERAL | OPTIONAL | COMMANDS ] * LABELS Labels in Robocomm scripts are created by starting a line with a colon character. Many script commands allow command control to quickly jump forward or backward within a script file be referencing a label name. Labels must be on a line all by themselves. Robocomm will use all text contained between the colon character and the first space or end of line as the label name. The following are all examples of valid label lines: :ERROR (something must have gone wrong) :start :This-Is-An-Example-Of-A-Very-Long-Label-Indeed! * MACROS Most commands ask for text to be supplied as an argument. Whenever that text is contained within quotes, several "macros" can be used with specific meanings. All Robocomm script macros are indicated by surrounding text by percent signs. At script run-time, these macros will be replaced with the appropriate text before being used by the specified script command. _________________________________________________________________ Robocomm 4.1 - Script Language Reference Page: 2 1. %ID% - Translated to the BBS ID of the currently connected BBS. 2. %QWKDIR% - Translated to the configured download directory for mail packets. 3. %REPDIR% - Translated to the configured directory for outgoing replies. 4. %DLDIR% - Translated to the configured file download directory. 5. %ULDIR% - Translated to the configured file upload directory. 6. %DOW% - Translated to three characters indicating the current day of the week: MON,TUE,WED,THU,FRI,SAT,SUN 7. %DOM% - Translated to two numeric characters indicating the current day of the month. Range 01-31. 8. %MONTH% - Translated to three characters indicating the current month: JAN,FEB,MAR,APR,MAY,JUN,JUL,AUG,SEP,OCT,NOV,DEC 9. %NMONTH% Translated to two numeric characters indicating the month of the year. 10. %YEAR% - Translated to 4 numeric characters indicating the current year, e.g. 1991 11. %BBS##% - Translated to field number ## from the Directory-BBS record for the currently connected BBS. See Appendix "A" for a complete list of the BBS## macros. a) ## is the field from BBS40.DBF to return. 12. %P##% - Translated to the text parameter number ##, which was entered by the user when he/she created the currently running "execute script" agenda item. 13. %WC#% - Translated to Wildcat Command number #. * PARAMETERS With Robocomm, you can set up scripts which prompt the user for input when an "Execute Script" agenda item is _________________________________________________________________ Robocomm 4.1 - Script Language Reference Page: 3 being created. To do this, simply embed a statement similar to the following in your script file: PARAMETER "Enter your mother's maiden name:" When the user is creating the agenda, Robocomm will pause and ask the question specified between the quotes on the parameter line. The user will be allowed to enter up to 128 characters of any type in response to the question. To access the text input by the user, the script author embeds %P##% into his/her script file at any location where double quotes are to surround text. In the text above, ## represents the parameter number you wish to access. Continuing our example, to send the user's mother maiden name to the BBS you would use the following script command: SEND "%P1% In the example above the number "1" is specified to access the parameter text input in response to the first PARAMETER statement which is contained in the file. It is important to understand that Robocomm numbers the parameters so that they correspond to the same order as the PARAMETER statements within the text file. For a working example of PARAMETERs, examine the file SET_PCB.RS. II. Script Commands * CAPTURE "<cFile>" [OVERWRITE | APPEND] Opens capture file <cFile> and closes any capture file previously opened. Options: If OVERWRITE is specified, then the contents of any existing <cFile> will be replaced with the captured data. If APPEND is specified Defaults: <cFile> defaults to the current BBS ID with a CAP extension. The file creation mode defaults to APPEND. Example: _________________________________________________________________ Robocomm 4.1 - Script Language Reference Page: 4 CAPTURE "\ROBOCOMM\LOGS\CHESSGAM.CAP" OVERWRITE See Also: CLOSE * CD "<cDirectory>" Changes the current DOS drive and/or directory to <cDirectory>. Note: The Robocomm home drive and directory is always restored upon termination of script processing. Note: If the specified directory does not exist, Robocomm will make a log notation and abort the script processing. Example: CD "F:\TEMP\LISTS" See Also: MD RD * CLEAR [WATCHES] Clears all text watches installed via the WHEN command. Robocomm adds another watch item each time you issue the WHEN command from within a script. Deactivating a watch with the DISABLE command does not actually remove it from the list of text items which are compared to all incoming text. The CLEAR command should be used when you wish to discard the entire "watch list." The next WHEN command issued after a CLEAR will install watch #1. See Also: WHEN WAITFOR DISABLE ENABLE * CLOSE _________________________________________________________________ Robocomm 4.1 - Script Language Reference Page: 5 Closes any open capture file started via the CAPTURE command. If no capture file is currently active, the command is ignored. See Also: CAPTURE * COPY "<cSource>" [TO "<cTarget>"] Copies the file <cSource> to <cTarget>. If <cSource> cannot be opened or <cTarget> cannot be created a notation will be made in ROBOCOMM.LOG and script processing will be terminated. If <cTarget> already exists when the copy begins, it will be replaced with the contents of <cSource>. <cTarget> is optional, and if not specified, Robocomm will attempt to create a file with the same name as <cSource> in the current directory. Note: Attempting to COPY a currently open log or capture file is not possible and will result in the termination of script processing. Examples: COPY "C:\ROBOCOMM\GROUPONE.CAP" "C:\OLDCAPS\GROUPONE.CAP" COPY "%QWKDIR%%ID%.PTR" See Also: ERASE RENAME * DELAY <nSeconds> Pauses all script processing for <nSeconds>. No characters are read from the active communications port. Absolutely nothing happens, other than a not-so-dramatic pause. Keep in mind that the BBS may still be sending characters to Robocomm. If so, they will be stored in Robocomm's internal communications buffer until the end of the delay period. Note: If you set a long delay period, keep in mind that Robocomm may appear to be "frozen" to some users because the timeout counter in the upper corner of the screen will not update. If you are worried that some user may _________________________________________________________________ Robocomm 4.1 - Script Language Reference Page: 6 over-react to this condition, consider placing a MESSAGE command to place a notation in the lower log window before the call to DELAY. Example: DELAY 10 * DISABLE <nWatch> Temporarily disable a watch installed via the WHEN command. The contents of watch number <nWatch> will not be compared against incoming text during subsequent WAITFOR processing. The watch may be reactivated later with the ENABLE command. Example: DISABLE 5 See Also: WHEN WAITFOR ENABLE CLEAR WATCHES * DOWNLOAD ["<cFileSpec>"] [USING "<cProtocol>"] [RESUMEOK | OVERWRITE] Downloads a file to <cFileSpec> using <cProtocol>. <cFileSpec> may be a complete filename or a download path. If the protocol you select is a batch protocol and the BBS sends a file of a different name than that specified in <cFileSpec>, Robocomm will attempt to rename the file to the specified name after the download is complete. <cFileSpec> defaults to the currently defined file download directory. USING "<cProtocol>" is an optional parameter which specifies the protocol or batch file to use for the transfer. All of Robocomm's internal protocols, "ZMODEM", "YMODEM","YMODEM-G", "ASCII" are valid values for <cProtocol>, as is the name any batch file which uses Robocomm's standard method for communicating with batch files. _________________________________________________________________ Robocomm 4.1 - Script Language Reference Page: 7 <cProtocol> defaults to the currently defined file download protocol. If you are using Robocomm's internal ZMODEM protocol, you may inform the protocol that it is OK to attempt to resume an aborted transfer by adding the RESUMEOK directive to the DOWNLOAD command line. The existing portion of the file will be verified with the sending file and a resume will be attempted if possible. If you anticipate that the DOWNLOAD command will be receiving a file which already exists, then you may specify the OVERWRITE directive to replace the existing file with the file being downloaded. Examples: DOWNLOAD This command will use the currently defined file download path and protocol to receive a file. DOWNLOAD "%ULDIR%" USING "YMODEM-G" Downloads files to your configured file upload directory using Robocomm's internal Ymodem-G. DOWNLOAD USING "ROBORH" Downloads files to the default file download directory using the HS/Link external batch protocol. * ENABLE <nWatch> Resume processing of a watch previously suspended with the DISABLE command. If text read from the communications port during a WAITFOR matches the contents of watch number <nWatch> the previously indicated action will be executed. Example: ENABLE 3 See Also: WAITFOR _________________________________________________________________ Robocomm 4.1 - Script Language Reference Page: 8 WHEN DISABLE * ERASE "<cFile>" Erases <cFile> from disk. No error is returned and script processing will continue normally if <cFile> does not exist. If <cFile> does exist, it will be deleted. * EXIT <nReturnVal> Quits script processing and returns to the agenda control level. If <nReturnVal> is greater than zero, a notation will be made in the log and the "Execute Script" agenda item will be marked with an exclamation mark. The exclamation mark implies an error, and will prevent the agenda item from being deleted if it has "temporary" status. <nReturnVal> defaults to zero. If the script returns zero to the agenda processing module, the task will be marked as completed. This means that if the "Execute Script" agenda item was temporary it will be removed from the agenda on its next "re-set" operation. * GOSUB <label> Branches control flow to the line following the specified <label>. Control will remain at the specified level until a RETURN statement is encountered, at which time agenda processing will resume with the first valid command line immediately following the GOSUB statement. GOSUBs may be nested 4096 levels deep. Example: The following script lines, would send "Robocomm 4.1" to the BBS: GOSUB firstpart SEND "4.1" :FIRSTPART SEND "Robocomm " RETURN _________________________________________________________________ Robocomm 4.1 - Script Language Reference Page: 9 See Also: GOTO RETURN * GOTO <label> Pass the sauce. Spaghetti code lives! The ubiquitous GOTO command will branch script control to the line following the specified <label> and never look back. It's up to you to keep track of where the program's going when you use GOTOs. Example: The following code produces an infinite loop, from which Robocomm will never recover without a loving keystroke from you. :Label1 Send "Even robots can get " GOTO Label3 :Label2 Send "Dizzy!!! |" GOTO Label1 :Label3 Send "a little bit " GOTO "Label2 NOTE: Pressing the F3 "Abort Agenda" or "F1" jump to terminal keys during a runaway script are your escape hatches in instances like these. See Also: GOSUB Two Guys From Italy. * HANGUP Terminates the current connection by hanging up the modem. Script processing continues after the disconnection with the line following the hangup command. If a WAITFOR command is issued subsequent to a disconnection, Robocomm will assume that you did not intend to drop carrier and will abort the current script. _________________________________________________________________ Robocomm 4.1 - Script Language Reference Page: 10 * IF [NOT] <condition> ["<argument>"] <command> Evaluates <condition> and executes the script command <command> if it is true. The optional NOT parameter may be added immediately following the keyword IF when you want to execute <command> only when <condition> is not true. 1. EMPTY Use this command to test the existence of a parameter. If a parameter is not passed (i.e. left blank on the agenda editing screen), then EMPTY will be true. Examples: IF EMPTY "%P1%" GOTO ERROR IF NOT EMPTY "%P2%" SEND "%P2%|" 2. EXIST Use this test for the existence of a file. Examples: IF EXIST "C:\QWKS\GROUPONE.KEY" GOTO SENDKEY IF NOT EXIST "%ID%.RLY" GOSUB GETMSGS IF EXIST "ALLFILES.ZIP" RENAME "ALLFILES.ZIP" TO "ALLFILES.OLD" 3. DAY Robocomm can test today's day of week with the use of any of these keywords. Examples: IF NOT DAY "SUN" GOTO WORK IF DAY "SUN" GOTO CHURCH IF DAY "MON" RENAME "BULL_1.CAP" TO "BULL_1.MON" 4. DIR _________________________________________________________________ Robocomm 4.1 - Script Language Reference Page: 11 Use this option test for the existence of a subdirectory on a disk. Examples: IF DIR C:\SCRIPTDIR\TEMP\ GOTO KILLDIR IF NOT DIR \TEMP MD \TEMP 5. CONNECTED Tests if the modem is currently connected with a BBS system. Examples: IF CONNECTED SEND "BYE|" IF NOT CONNECTED GOSUB CLEANUP 6. ERRORLEVEL Tests to see is the last command executed with the RUN command set an errorlevel greater than zero. IF ERRORLEVEL GOTO TRYAGAIN IF NOT ERRORLEVEL GOTO SUCCESS 7. YES Checks to see if a parameter is equal to Y,y,YES, Yes or yes. IF YES "%P3%" GOTO SENDREP * IMPORT ["A"|"D"] "<cFile>" [EXISTONLY] This command allows you to import the <cFile> file listing into Robocomm's "Available Files" or "Downloaded Files" directory. The optional letter "A" or "D" tells Robocomm which file directory to send the file names to. By default Robocomm sends file listings to the "Available Files" directory. The optional EXISTONLY clause tells Robocomm to only import those files that can be located in your configured download, upload or search directories. Example: IMPORT "D" "VAMPIRE.CAP" EXISTONLY This command tells Robocomm to import VAMPIRE.CAP into the "D"ownloaded files directory, adding only those files to the directory that can be found in any of Robocomm's configured search directories. NOTE: If you are creating a file list in a script, you can use the CONFSTAMP "<text>" script command to write the current conference marker to the capture file. _________________________________________________________________ Robocomm 4.1 - Script Language Reference Page: 12 IMPORT "GIFS.CAP" This command tells Robocomm to import the file GIFS.CAP into the available files directory. * JOIN "<cConference>" Attempts to join the conference specified, using the prompts defined on the Directory-BBS-Prompts screen for the currently connected BBS. Script processing is aborted if the Join attempt is unsuccessful or cannot be verified. Examples: JOIN "0" Attempts to navigate to the "Main Board" prompt. JOIN "Robocomm" Attempts to navigate to the "Robocomm Conference Command" prompt. * MD "<cDirectory>" Attempts to create a subdirectory named <cDirectory>. Note: If the specified directory cannot be created, Robocomm will make a log notation and abort the script processing. Example: MD "C:\TEMPDOWN" See Also: CD RD * MESSAGE "<cString>" Posts <cString> as a message in ROBOCOMM.LOG. _________________________________________________________________ Robocomm 4.1 - Script Language Reference Page: 13 * NOTES "<cFile>" This command places the contents of <cFile> into Robocomm's internal data structures so that the data can be viewed later via Robocomm's "Notes" command on the Directory-BBS screen. NOTE: Robocomm will not import a file longer than 10,240 characters. Attempts to do so will be ignored. Example: NOTES "%ID%.NOT" * PARAMETER [nNumber] "<cPrompt>" Defines a parameter question that will be used to prompt the user for input at agenda creation time. <cPrompt> may be up to 40 characters in length. The user will be allowed to input up to 128 characters. NOTE: The optional nNumber argument is really only for readability purposes and is not examined by Robocomm at all. Robocomm numbers parameters sequentially, in the order they are encountered within the script file. Example: PARAMETER "Heard any good jokes lately?" * PASSWORD "<cPassword>" Updates the password in the Directory-BBS record for the current BBS with <cPassword>. Example: PASSWORD "NewPass" * RD "<cDirectory>" Attempts to remove subdirectory <cDirectory>. The specified directory must be completely empty, with no hidden files or subdirectories. _________________________________________________________________ Robocomm 4.1 - Script Language Reference Page: 14 Note: If the specified directory cannot be removed, Robocomm will make a log notation and abort the script processing. Example: RD "C:\GONNER" See Also: CD MD * RENAME "<cfile>" [TO] "<cNewName>" Attempts to rename <cFile> to <cNewName>. Just as with DOS, this command will fail if a file names <cNewName> already exists. The TO clause is optional, and functions only to enhance readability. * RENUMBER "<cFile>" [<nCount>] Uses Robocomm's internal renumbering scheme to maintain a <nCount> archived versions of <cFile>. <nCount> defaults to 1 if not specified. Example: RENUMBER "VAMPIRE.CAP" 5 * RETURN Causes script process control to return to the first valid command line immediately following the most recent GOSUB command. Example: IF SUN GOSUB GETFILES SEND "BYE|" EXIT 0 :GETFILES MESSAGE "It's Sunday. Downloading and processing Allfiles" RENUMBER "%DLDIR%ALLFILES.ZIP" 2 _________________________________________________________________ Robocomm 4.1 - Script Language Reference Page: 15 SEND "D;ALLFILES.ZIP|" DOWNLOAD RETURN * RUN "<cDosCommand>" [KEYBOARD "<cKeyString>"] Shells to DOS and runs the command <cDosCommand>. If you need to test the result of the called process, the ERRORLEVEL set by the called program is retained by Robocomm to be queried with the IF ERRORLEVEL script command. Note: Robocomm's current drive and directory is always restored automatically after the called process returns control. Examples: RUN "Rexclude c:\download" CAUTION: If you do not plan on exploring the KEYBOARD clause, detailed below, be sure not to call any process from within Robocomm that will require a keypress. If you do this and aren't around to manually press the required key, Robocomm will be unable to recover and all processing will halt until you show up to rectify the situation. Using the KEYBOARD clause: In cases where you really want to run an external program that requires keystrokes, the optional KEYBOARD command can help. This command stuffs the keyboard by temporarily taking over BIOS interrupt 16h. Thus, you can automate all or part of the program that you call with Robocomm's RUN command. This capability was inspired by a memory resident program called Key-Fake by Charles Petzold and copyrighted by Ziff-Davis Publishing Company. Mr. Petzold did an excellent job and Robocomm imitates, with a few enhancements, Mr. Petzold's method of defining the keys to stuff the keyboard. The KEYBOARD command function works with almost any programs you might want to call, except for those rare programs that directly take over the keyboard. _________________________________________________________________ Robocomm 4.1 - Script Language Reference Page: 16 The KEYBOARD <cKeyString> is a character string parameter. This character string can contain: 1) embedded character strings. 2) named keys within curly brackets. 3) the number 0 by itself. 4) the number 1 by itself. 1) Embedded character strings: Characters within inner quotes (either single or double quotes) are normal ASCII characters. KEYBOARD "'EXIT'"would stuff the keyboard with the four keys 'E', 'X', 'I', and 'T'. Normally, these characters are limited to those alphabetical, numeric, and symbol characters that can be typed at the keyboard. Keys such as <F1> and <Insert> cannot be specified this way. You can specify other non- keyboard characters such as graphics characters which are not normally available from the keyboard. If non- keyboard characters are specified, KEYBOARD will attempt to pass them to the called program, but some programs may not be able to accept them. Please note that the character string passed to KEYBOARD begins and ends with double quotes ("), and that the inner string begins and ends with single quotes ('). 2) Named keys within curly braces: In order to specify keys such as <F1>, <Insert>, and <Ctrl-A>, you must specify them within curly braces. KEYBOARD can handle every possible key combination that converts to a keycode. Some keys such as the <PrintScreen> and <NumLock> have no keycode value and cannot be stuffed with KEYBOARD. When specifying the keys, case is not important. You may use uppercase, lowercase, or mixed case. The keys are specified with the form {[<switch>-]keyname} where keyname is the name of the key optionally preceded by one of the switch keys: <Shift>, <Ctrl>, <Alt>. Only one switch key can be specified because they are mutually exclusive. When more than one switch key is pressed at a time, the _________________________________________________________________ Robocomm 4.1 - Script Language Reference Page: 17 <Ctrl> key overrides the <Shift> key and the <Alt> key overrides the <Ctrl> key. The following keys are valid: {F1}..{F12} {Shift-F1}..{Shift-F12} {Ctrl-F1}..{Ctrl-F12} {Alt-F1}..{Alt-F12} Note that F11 and F12 are only available on enhanced keyboards and may not be accepted by a program running on a computer with a standard keyboard. {Ctrl-A}..{Ctrl-Z} {Alt-A}..{Alt-Z} {Ctrl-0}..{Ctrl-9} {Alt-0}..{Alt-9} These keys correspond to the keys on both the numeric keypad and the QWERTY keyboard when a standard keyboard is in use. An enhanced keyboard can differentiate between the numeric keypad and the QWERTY keyboard if the software enables it to do so. If the software you're using requires that the numbers come from the numeric keypad, use the # symbol explained below. {<Symbol>} {Ctrl-<Symbol>} {Alt-<Symbol>} where <Symbol> is anyone of the 30+ symbols available on the keyboard such as !@#$%&*~_-+={}[]|\:;"'<>,.?. {Enter}, {Esc}, {Tab}, {Bksp}, {Space} {Ctrl-Enter}..{Ctrl-Space} {Alt-Enter}..{Alt-Space} {Home}, {End}, {PgUp}, {PgDn}, {Left}, {Right}, {Up}, {Down}, {Ins}, {Del} {Ctrl-Home}..{Ctrl-Del} {Alt-Home}..{Alt-Del} These keys are all found on the numeric keypad. {*Home}, {*End}, {*PgUp}, {*PgDn}, {*Left}, {*Right}, {*Up}, {*Down}, {*Ins}, {*Del} {Ctrl-*Home}..{Ctrl-*Del} {Alt-*Home}..{Alt-*Del} _________________________________________________________________ Robocomm 4.1 - Script Language Reference Page: 18 where the * symbol stands for the extra cursor control pad available on enhanced keyboards. These keys can only be specified when an enhanced keyboard is in use; these keys are not available on a standard keyboard. Use these keys when the software requires that the keypress be from the extra cursor control pad. {#0}..{#9}, {#.}, {#}, {#*}, {#-}, {#+}, {#Enter} {Ctrl-#0}..{Ctrl-#9}, {Ctrl-#.}..{Ctrl-#Enter} {Alt-#0}..{Alt-#9}, {Alt-#.}..{Alt-#Enter} where the # symbol stands for the numeric keypad. These keys can only be specified when an enhanced keyboard is in use; a standard keyboard does not differentiate the numeric keypad keys from their QWERTY keyboard counterparts. Use these keys when the software requires that the keypress be from the numeric keypad only. {SysReq} notice that the {SysReq} key is specified without the {Ctrl-} prefix. 3) The number 0 by itself: The number 0 by itself is a special symbol to KEYBOARD; it tells the function to report back to the called program, at that point, that the keyboard buffer is empty. This should be unnecessary for most programs, but if you find that at some point the called program seems to clear the keyboard buffer or lose keystrokes, you may need to use a 0 to fool the program into thinking the keyboard buffer is empty. By default, KEYBOARD stuffs a 0 key after each keystroke. This makes the external program think that the keyboard buffer is empty after each keystroke. This is necessary because some programs clear the keyboard buffer after each keystroke. 4) The number 1 by itself: The number 1 by itself is also a special symbol to KEYBOARD. It tells the function to wait for the user to hit a key before continuing; the keystroke is then passed directly to the external program. Obviously, this capability has limited usefulness in an unattended environment, but is useful when the user must make a choice or enter a secret code before KEYBOARD can continue stuffing more keys. _________________________________________________________________ Robocomm 4.1 - Script Language Reference Page: 19 Summary: All of these key definitions can be put in the same character string. You are currently limited to stuffing 250 keystrokes into the keyboard. Some programs take over the keyboard directly, which keeps Robocomm from stuffing the keyboard. There is nothing that can be done about these programs, but they are definitely in the minority. Example: Import Robocomm's TRANSFER.LOG into a dBASE database using FoxPro: RUN "foxproln" KEYBOARD "`USE TRANSFER.DBF` {ENTER} `APPE FROM TRANSFER.LOG` {ENTER} `QUIT` {ENTER}" In our doc file, that line wrapped to a second line, but in your script file, it should be all on one line. * SEND "<cString>" This command sends one or more characters to the BBS. Before sending the text, Robocomm will look for the existence of two special characters; the pipe "|", the carat "^" and the tilde "~". Use the pipe character whenever you would like Robocomm to send a carriage return. Use the carat to signify that the next character is a "control character." Use the tilde whenever you would like Robocomm to pause for on half second before sending the next character. Examples: SEND "^X^X~~~~^X^X" This example sends two "Control-X" characters, pauses for 2 seconds, and then sends another paid of Control-X characters. This is the key sequence that is commonly used to abort a file transfer. SEND "B|1|" This example sends the letter "B" followed by a carriage return (ASCII code 13), followed again by the number 1 and another carriage return. _________________________________________________________________ Robocomm 4.1 - Script Language Reference Page: 20 NOTE: Robocomm does not automatically append a carriage return to the text you specify between quotes. If a carriage return is required, you must supply it by ending the string with the | or ^M characters. SENDING RESERVED CHARACTERS: To send a tilde, carat or pipe character to the BBS as part of your send string, simply place a carat before the character. ^^ sends ^ ^~ sends ~ ^| sends | * SOUND <nFrequency> <nDuration> Creates a sound on the PC's speaker. <nFrequency> is a numeric value indicating the desired frequency, in the range of 37 to 32767. If not specified, <nFrequency> defaults to 500. <nDuration> is the amount of time to continue the sound, in 100ths of a second. NOTE: If the user has the speaker style option on Robocomm's General Configuration screen set to SILENT no sound will be produced. For the musical purists in the group, the following is a table of values to produce standard musical pitches: Pitch Frequency Pitch Frequency ---------------------------------------------------------- C 130.80 mid C 261.70 C# 138.60 C# 277.20 D 146.80 D 293.70 D# 155.60 D# 311.10 E 164.80 E 329.60 F 174.60 F 349.20 F# 185.00 F# 370.00 G 196.00 G 392.00 G# 207.70 G# 415.30 A 220.00 A 440.00 A# 233.10 A# 466.20 B 246.90 B 493.90 _________________________________________________________________ Robocomm 4.1 - Script Language Reference Page: 21 C 523.30 ---------------------------------------------------------- * STATISTICS "<cFile>" This command places the contents of <cFile> into Robocomm's internal data structures so that the data can be viewed later via Robocomm's "Statistics" command on the Directory-BBS screen. NOTE: Robocomm will not import a file longer than 10,240 characters. Attempts to do so will be ignored. Example: STATISTICS "%ID%.STS" * TERMINAL [NOKEY] [EXITON "<text>"] [DOORWAY] All parameters are optional. Their purposes are: NOKEY - Bypasses the alarm and the necessity to press a key after jumping to terminal. NOTE: The terminal mode "alarm" is actually a 60 second timer that will enable Robocomm to recover if no one is around to interact with the terminal. Using the NOKEY clauses disables this alarm, so Robocomm will jump to terminal mode and will not go back to automated processing until the user presses Alt-X or when the EXITON text is seen. (See below) EXITON - This command allows you to specify a text string that Robocomm will watch for whenever it is in terminal mode. If Robocomm encounters the specified text it will immediately exit the terminal mode and resume script processing. DOORWAY - This command causes the terminal to start with "Doorway" mode turned on. NOTE: You will need to Press [Alt =] to turn doorway mode off before you can exit with Alt-X. Examples: TERMINAL Goes into standard terminal mode, sounds alarm. TERMINAL NOKEY Goes into standard terminal with no alarm or keypress. TERMINAL DOORWAY Goes into Doorway mode terminal, sounds alarm. TERMINAL EXITON "<EXIT>" Goes into terminal. Automatically exits on <EXIT>. TERMINAL NOKEY DOORWAY EXITON "<EXIT>" You get the idea... * TIMEOUT <nSeconds> Sets the number of seconds that all subsequent WAITFOR commands will allow to pass while they watch for their intended string. If <nSeconds> elapses before the match is found, control will pass to the defined WAITFOR FAILURE clause, or, if none is defined, to the next executable statement in the script. Example: TIMEOUT 30 See Also: WAITFOR * TITLE "<cString>" Sets the script title that will appear in the Script Selection window on the agenda modification screen. _________________________________________________________________ Robocomm 4.1 - Script Language Reference Page: 22 Although this statement can appear anywhere within the script file, you should place it as the first line in the script, to make the Script Selection window pop-up as rapidly as possible. It's also a good idea to indicate the type of BBS system the script is designed to handle in the title. Example: TITLE "(PCBoard) This is a script title example!" * UPLOAD "<cFileSpec>" [USING "<cProtocol>"] Sends <cFileSpec> to the BBS using <cProtocol>. <cFileSpec> may be any valid path and/or filename, including wildcard characters. If the optional USING <cProtocol> clause is specified, then Robocomm will use the protocol specified. By default Robocomm will attempt to use configured file upload protocol. ASCII is a valid upload protocol type. Examples: UPLOAD "c:\qwks\%ID%.KEY" USING "YMODEM-G" UPLOAD "C:\OUTGOING\*.ZIP" UPLOAD "message.txt" USING "ASCII" * VENUE <cVenueCode> Attempts to move to the area of the BBS system specified by cVenueCode. Valid codes are: Code Description Systems -------- --------------------------------- ------- MSGS Go to the message sub-menu Wildcat FILE Go to the file sub-menu Wildcat MAIN Go to the Main Menu PCB/WC MAIL Go to the defined QWK door PCB/WC PRO Go to ProDoor PCB/Pro Examples: VENUE MAIL VENUE MSGS See also: _________________________________________________________________ Robocomm 4.1 - Script Language Reference Page: 23 JOIN * WAITFOR "<cString>" [FAILURE <command>] Watches for incoming text matching <cString> while simultaneously watching for any "watches" defined with the WHEN command. The amount of time that Robocomm watches for text is defined separately with the TIMEOUT command. If <cString> is recognized within the allotted time, Robocomm simply proceeds on to the next executable line in the script. If, however, <cString> is not recognized, Robocomm's subsequent behavior depends upon whether the optional FAILURE clause has been specified. If a FAILURE <command> has been specified, Robocomm will immediately process <command>. If no FAILURE command is specified, then an error message is inserted in the log and script processing is terminated. NOTE: Aside from the file transfer commands. WAITFOR is the only script command which actually retrieves incoming text from the comm port receive buffers. For this reason, you will see text scrolling in the online window only while a WAITFOR is being evaluated. NOTE: To copy a list of the currently active watches to the VERBOSE mode log in Robocomm, simply press [Alt-S] while Robocomm is watching for text. This feature will aid you greatly in debugging your scripts. Examples: The following script fragment sets up a number of watches via the WHEN command and demonstrates the use of the WAITFOR command in conjunction with them. ; A sample script to download ProDoor ZIPMail packets. ; ; FOR DEMONSTRATION PURPOSES ONLY -- NOT TESTED ; TIMEOUT 10 WHEN "MORE?" SEND "N|" WHEN "[ENTER] TO CONTINUE" SEND "|" WHEN "SCAN MESSAGES" SEND "N|" WAITFOR "COMMAND?" FAILURE GOTO ERROR TIMEOUT 600 SEND "ZIPM|" WHEN "NO MESSAGES" GOTO NOMAIL WHEN "NOT ENOUGH TIME" GOTO ERROR WHEN "PROTOCOL" SEND "Z|" WAITFOR "CTRL-X ABORTS" FAILURE GOTO ERROR _________________________________________________________________ Robocomm 4.1 - Script Language Reference Page: 24 RENUMBER "%QWKDIR%%ID%.ZPM" 5 DOWNLOAD "%QWKDIR%%ID%.ZPM" EXIT 0 :ERROR HANGUP EXIT 1 ; End of script. See Also: WHEN TIMEOUT * WAITUNTIL ["<cTime>"] ["<cDate>"] Pauses script execution until a specified date and/or time. <cTime> is the time of day to start, in 24 hour format HH:MM <cDay> is the date to start in MM/DD/YY or MM-DD-YY format. Both parameters are optional, but at least one must be specified. If <cDate> is not specified, it defaults to the current date. If <cTime> is not specified, it defaults to "00:00" (Midnight). Examples: WAITUNTIL "06:00" WAITUNTIL "12:00" "12/13/91" WAITUNTIL "12/01/91" * WHEN "<cString>" <command> Creates an incoming text watch for <cString> and executes <command> whenever it is seen. WHEN commands are valuable when prompts from the BBS may come in random order or when a standardized response to a prompt should be sent whenever a certain prompt is received from the BBS. It is important to understand that the WHEN command merely posts <cString> and <command> for evaluation by the WAITFOR _________________________________________________________________ Robocomm 4.1 - Script Language Reference Page: 25 command. Thus, WHENs are only valid while a WAITFOR is currently being evaluated. Example: See example under the WAITFOR command. See Also: WAITFOR DISABLE ENABLE CLEAR _________________________________________________________________ Robocomm 4.1 - Script Language Reference Page: 26 ----------------------- SCRIPT.DOC - APPENDIX A ----------------------- Directory-BBS Field Macros -------------------------- The following %BBS??% macros are all to non-prompt related items: Macro # Description ------- ---------------------------------------------------- 1 The BBS Robocomm/Mail ID. (duplicated by %ID%) 2 The BBS Name 3 Phone Number #1 \ 4 Phone Number #2 |-- Dialing macros A-J NOT expanded. 5 Phone Number #3 / 7 Login Password 13 Login Name 17 Qmail Door Conference 19 File Upload Protocol 20 File Download Protocol 21 Mail Door Upload Protocol 22 Mail Door Download Protocol 60 PC-Pursuit outdial city 63 Command to Open Mail Door (Wildcat!) or Door Number/Name (PCBoard) 66 Upload area (Wildcat! only) ------------------------------------------------------------------------ The Following BBS?? Macros are the defined prompt definitions for PCBoard Systems: 29 Language to use 30 Help prompt 31 Do you want graphics 32 More? 33 Scan Messages 34 Pause - "Enter to Continue" 35 Main Board Prompt 36 Confernce ID string (# translated to conference number) 37 Upload file description 38 No Protocol Defined 39 Start Transfer 40 Mail Door Main Command 41 Start Mail Download 42 Start Mail Upload 43 Packet Transfer Confirmation. 44 No Mail to Download 45 Enter First Name 46 Enter Password (logon) 47 Message Menu Prompt 48 Download File Not Found 49 Generic Command (usually "Command") 50 Duplicate Upload 51 Insufficient security to download (restricted access) 52 Not enough time/bytes to download. 53 Upload file not accepted 54 ProDoor: Enter Upload Description 55 <not in use> 56 ProDoor: Main Board Command 57 <not in use> 58 ProDoor: Start Transfer 59 Front End Prompt (Usually "DOOR #") 70 Front End Mail Program (Robo sends 2 ESC characters) 71 Not enough time to download mail ----------------------------------------------------------------------- The Following BBS?? Macros are the defined prompt definitions for Wildcat! Systems: 29 Read Bulletins? 30 View Mail? 31 Location Confirmation (are you xxxx from xxxx?) 32 Press Enter to Continue 33 Enter Birthday 34 Pause 35 Main Menu 36 Confernce ID string (# translated to conference number) 37 Upload file description 38 Bulletin Menu 39 Start File Download 40 Mail Door (TomCat) Command Prompt 41 Start Mail Download 42 Start Mail Upload 43 Packet Transfer Confirmation. 44 No Mail to Download 45 Enter First Name 46 Enter Password (logon) 47 Message Menu Prompt 48 File Name to Download 49 Read Newsletter? 50 Duplicate Upload 51 Upload file not a duplicate 52 Logon name failure 53 Start file upload 54 File Menu 55 Enter Last Name 56 Phone number confirmation 57 <not in use> 58 D/L File Found 59 Front End Prompt (Usually "DOOR #") 70 File Upload Rename 71 Extended Descriptions 72 File Keywords 73 Not Enough Time to Download Mail 74 Choose Upload Area 75 Not Enough Time to Download 76 Not Enough Bytes to Download 77 Not Enough Credit to Download 78 Password protect upload question ------------------------------------------------------------------------------ The following %WC?% macros are the defined commands for the currently connected Wildcat BBS system: Number Command Default ------ -------------------------------------------- ------- 1 Quit from FILE or MESSAGE menu to MAIN menu. Q 2 Go to the MESSAGE menu from the MAIN menu. M 3 Go to the FILE menu from the MAIN menu. F 4 Start file download sequence D 5 Start file upload sequence U 6 "Info Scan" a downloadable file I 7 Start the new file scan sequence N 8 Log off from FILE, MESSAGE or MAIN menus. G 9 Start conference join sequence J Example: ; Go to the file menu SEND "%WC3%|"